EMP File Utility

In this section:

About the EMP File Utility

The Environment Manager Personalization File Utility (EMP File Utility) imports and exports files to and from the Environment Manager Personalization database using a command-line interface. Before the tool can be used, a valid connection string to the database must be defined. The user specified in the connection string must have the privilege to read, write, and run stored procedures in the database. The simplest privilege is "dbowner".

The utility accesses the database directly and does not use a Personalization Server.

This is a low level tool that uses elements of scripting in the command-line interface to input commands and set parameters. A knowledge of command-line utilities and scripting is an advantage when using this tool.

Requirements

A username and password of a user with access to the database tables is required because the utility accesses the database directly. Using the Personalization service account will not work.

Supported software versions

The EMP file utility no longer supports older versions of Environment Manager. The 8.5 utility can only be used on software version 8.5.

Windows Settings Group Support

The file utility may be used to import and export files from windows settings groups contained in the parent Windows Settings profile. To do this the application name is replaced by the Windows setting group name prefixed by "wsg:". For example, to import and export from the Windows Setting group named Appearance and Personalization, specify wsg:Appearance and Personalization as the application name.

Usage Scenario

A typical scenario is when a specific user or group requires that a certain file is updated through a batch process rather than via a user interface. The EMP File Utility can also be used in conjunction with Environment Manager Policy Configuration to directly manipulate the users settings within the database.

Export Files from a Database

A valid connection string to the database must be defined in the environment variable EMPFileUtilConnectionString in the same command window in which EMPFileUtil is run. This procedure shows how to set the environment variable and then run the utility.

  1. Select Start > AppSense > Environment Manager > Tools > EMP File Utility.
  2. On the command line, enter SET EMPFileUtilConnectionString=<connection string>

    For example, SET EMPFileUtilConnectionString=Data Source=(local);Initial Catalog=PersonalizationServer;Integrated Security=SSPI

  3. Press Enter.

    This environment variable can also be set globally in the System Properties. For Windows Vista and above, right-click Computer on the Start menu and select Properties. Select Advanced system settings, click the Advanced tab and select the Environment Variables button.

  4. In the command line, enter a command in the following format: EMPFileUtil EXPORT <username> <usergroup> <application> <databaseroot> <outputfolder>

    Where:

    Parameters Definition
    <username> The user’s name with preceding domain, for example, Ivanti\smithj
    <usergroup> The personalization group for the user, for example, “Default Users”
    <application> The name of the application or group (not the name of the executable, although it may be the same, for example Notepad), or the name of the Windows Settings group prefixed by “wsg:”.

    If the name contains spaces, the entire parameter, including the wsg:, must be included in quotation marks The following reserved application names are recognized:

    • Certificates (for Legacy Certificates profile)
    • Legacy Certificates
    • Windows Settings
    • Windows Personalization (for Windows Settings profile)
    • Legacy Session Data
    <databaseroot> The root of the file tree to be exported in “raw” format, for example, {CSIDL_APPDATA}.

    The value * (asterisk) may be used here to export all of the files in the application group. This also exports the registry file “settings.fbr” (or “registry.fbr” in the case of a Windows Setting group). These files should be re-imported only to the same user because they contain the user’s SID.

    Note; In such cases it might be more appropriate to use the EMP Registry Utility for transfer of registry settings.

    See EMP Registry Utility for further details.

    <outputfolder> The folder where the files are to be exported. A directory structure is built here matching the one in the database. Relative paths can be used, for example, a dot refers to the current path.

    Existing files are not overwritten and folders are created as required.

    Parameters Definition

    Parameters must be enclosed in quotes if they include embedded spaces.

  5. Press Enter to export all applicable files.

Import a File to the Database

Select Start > Ivanti > Environment Manager > Tools > EMP File Utility.

On the command line enter a command in the following format:

EMPFileUtil IMPORT <importdescription>.xml

The XML file contains information about users, application groups, and files to be loaded into the database.

There can be one XML file per user, or lots of users in the same file.

There can be one or more <User> elements under the top-leve l<Users> element. Each User element can specify multiple Personalization groups (User groups) for a user if required.

Multiple applications can be specified under the <PersonalizationGroup>. Each application has a folder where the utility finds the files to read - the RootFolder attribute.

Element Attribute Meaning
User Name User name in the form domain\user. This user need not exist if the SID is specified. The user need not have logged on to the Personalization server previously.
RetrieveSID Value is “yes” or “no”. If “yes”, EMPFileUtil will check AD (if in a domain) or the local machine (if not) to find the user's SID.
SID User's Sid, required if RetrieveSID=”no” has been specified.
PersonalizationGroup Name Name of the group to which the user and applications are to be loaded. This group must exist already. Note that you will create redundant data if the memberships do not put the user in the group.
Application Name Name of the application, application group or Windows Settings group preceded by “wsg:”. A group must be assigned to the Personalization Group or EMPFileUtil reports an error. Reserved application names (as listed for export above) may be used, but note that importing into a legacy profile will only affect legacy clients.
Type “Single” for an application or “group” for an application group.
DeleteExisting “Yes” or “no”. If the application already exists with data for the user/group, specifying “yes” will cause EMPFileUtil to delete all the old data. If “no”, new files will be added. If a new file has the same name and path as the old, a duplicate key error is generated and processing stops.
  Path where files to be imported are situated. The root must contain subdirectories of the form {CSIDL_xxx}, and no files. Below this anything is allowed and will be loaded into the database. Registry files cannot be loaded - this must be done instead with EMPRegUtil.

Personalization Analysis

Once the XML file has been imported you can drill into the users settings using the Personalization Analysis too.